Web Tier Updates for Annotation Layers

Overview

The C#, PHP, and JSP web tiers have been updated to support the requirements of the new client side feature, annotation layers. To accomplish this, a new class with a REST interface was created:

MarkupLayers Class: Provides a REST API for creating, reading, updating, and deleting persisted annotation layers. Annotation layers are JSON objects that are saved from the HTML5 viewer and can later be loaded back into it. The filename for this class is named somewhat differently in each web tier:

C#	PccViewer.WebTier.Core.HttpMarkupLayers.cs
PHP	MarkupLayers.php
JSP	MarkupLayers.java

REST Interface to MarkupLayers Class

GET /MarkupLayers/{viewingSessionId}?{optional parameters...}

Returns a list of layers on the server associated with a particular document. The optional parameters are derived from the metadata parameter passed to ViewerControl.

Possible Responses:

200 OK

Example	Copy Code
Array of JSON data [ { "name" {string}: the name of the markup layer (as assigned by the user) "layerRecordId" {string}: a unique ID for that particular resource "originalXmlName" {string}: the name of the original XML file associated with the marks stored in this layer, or an empty string if no XML file is associated }, { "name": "User 1’s Layer", "layerRecordId": "guid", "originalXmlName": "my marks" }, ... ]

Example

Copy Code

Array of JSON data
[
  {
      "name" {string}: the name of the markup layer (as assigned by the user)
      "layerRecordId" {string}: a unique ID for that particular resource
      "originalXmlName" {string}: the name of the original XML file associated with the marks stored in this layer, or an empty string if no XML file is associated
  },
  {
      "name": "User 1’s Layer",
      "layerRecordId": "guid",
      "originalXmlName": "my marks"
  },
  ...
]

502 Bad Gateway

Example	Copy Code
None

580 Server Error

Example	Copy Code
{ "errorCode" {string}: a descriptive code concerning the error, "errorMessage" {string}: a useful message about what happened, such as a file read error }

GET /MarkupLayers/{viewingSessionId}/{layerRecordId}

Returns a specific markup layer record.

Possible Responses:

200 OK

Example	Copy Code
JSON Data for MarkupLayer

404 Not Found

Example	Copy Code
None

502 Bad Gateway

Example	Copy Code
None

580 Server Error

Example	Copy Code
{ "errorCode": a descriptive code concerning the error, "errorMessage" {string}: "A useful error message about the server error.", "layerRecordId": {layerRecordId} }

POST /MarkupLayers/{viewingSessionId}

Creates a new markup layer, as defined in the request body.

Body:

Example	Copy Code
JSON data for MarkupLayer

Possible Responses:

201 Created

Example	Copy Code
{ "layerRecordId": "guid" }

502 Bad Gateway

Example	Copy Code
None

580 Server Error

Example	Copy Code
{ "errorCode" {string}: a descriptive code concerning the error, "errorMessage" {string}: exception message }

POST /MarkupLayers/{viewingSessionId}/{layerRecordId}

Request Headers:

Example	Copy Code
X-HTTP-Method-Override: PUT

Updates an existing markup layer. Note: the implementation allows for this to be an actual PUT verb, if supported.

Body:

Example	Copy Code
JSON data for MarkupLayer

Responses:

200 OK

Example	Copy Code
None

404 Not Found

Example	Copy Code
None

502 Bad Gateway

Example	Copy Code
None

580 Server Error

Example	Copy Code
{ "errorCode" {string}: a descriptive code concerning the error, "errorMessage" {string}: exception message, "layerRecordId": {layerRecordId} }

POST /MarkupLayers/{viewingSessionId}/{layerRecordId}

Request Headers:

Example	Copy Code
X-HTTP-Method-Override: DELETE

Deletes a markup layer from storage. Note: the implementation allows for this to be an actual DELETE verb, if supported.

Body:

Example	Copy Code
None

Possible Responses:

204 No Content

Example	Copy Code
None

404 Not Found

Example	Copy Code
None

502 Bad Gateway

Example	Copy Code
None

580 Server Error

Example	Copy Code
{ "errorCode" {string}: a descriptive code concerning the error, "errorMessage" {string}: exception message, "layerRecordId": {layerRecordId} }

Markup Layer Schema

The annotation layer schema is shown below. Please note:

The marks array or the comments array can be an empty array (if the user adds marks, but no comments; or if the user adds comments to another user’s layer’s mark(s), but adds no marks).
The comments for marks in other layers are stored in the comments array, and the comments for marks in the current layer are stored in the comments array (not under the particular mark).

Example	Copy Code
{ name {String}: The friendly layer name originalXmlName {String}: If this layer was converted from an XML file, then the descriptive XML name will be stored here data {Object.<key, string>}: a property bag of user-defined values marks {Array.<Mark JSON>}: [ { uid {String}: A global unique ID for this mark type {String}: A value from PCCViewer.Mark.Type denoting the mark type pageNumber {Number}: The page that the mark is located on creationDateTime {String}: ISO string of the created time modificationDateTime {String}: ISO string of the last modified time interactionMode {String}: value from PCCViewer.Mark.InteractionMode data {Object.<key, string>}: a property bag of user-defined values conversation {Conversation}: { data {Object.<key, string>}: a property bag of user-defined values } ... }, {...}, {...} ], comments {Array.<Comment>}: [ { markUid {String}: The global unique ID for the mark this comment is under data {Object.<key, string>}: a property bag of user-defined values creationDateTime {String}: ISO string of the created time text {String}: The text of the comment }, {...}, {...} ] }

Example

Copy Code

{
 name {String}: The friendly layer name
 originalXmlName {String}: If this layer was converted from an XML file, then the descriptive XML name will be stored here
 data {Object.<key, string>}: a property bag of user-defined values
 marks {Array.<Mark JSON>}: [
   {
     uid {String}: A global unique ID for this mark
     type {String}: A value from PCCViewer.Mark.Type denoting the mark type
     pageNumber {Number}: The page that the mark is located on
     creationDateTime {String}: ISO string of the created time
     modificationDateTime {String}: ISO string of the last modified time
     interactionMode {String}: value from PCCViewer.Mark.InteractionMode
     data {Object.<key, string>}: a property bag of user-defined values
     conversation {Conversation}:
       {
         data {Object.<key, string>}: a property bag of user-defined values
       }
     ...
   }, {...}, {...}
 ],
 comments {Array.<Comment>}: [
   {
     markUid {String}: The global unique ID for the mark this comment is under
     data {Object.<key, string>}: a property bag of user-defined values
     creationDateTime {String}: ISO string of the created time
     text {String}: The text of the comment
   }, {...}, {...}
 ]
}